E.M.Computergraphic Phase 4

home *** CD-ROM | disk | FTP | other *** search

/ E.M.Computergraphic Phase 4 / Phase 4 - Desktop Video Dreams (E. M. Computergraphic)(1996).iso / utilities / jacosub / jscripts.readme < prev next >

Wrap

Text File | 1996-01-02 | 34KB | 643 lines

JACOsub 1.5 SCRIPT FILE FORMAT SPECIFICATION ============================================ Here is the complete JACOsub script file format specification. It's not complicated (unless you want it to be) and quite flexible. Check out the sample script (demo.js) that came with this software; it demonstrates many of the things you can do with a script. Format Conventions ------------------ 1. Space characters (white space) may consist of spaces or tabs. Any line in a script file may contain any amount of white space in front of, behind, or in between parameters or words. 2. A line cannot be more than 511 characters in length. 3. Lines in the file may be either blank lines, compiler commands, or timing lines for the script. All these are explained below. 4. BLANK LINES or lines containing white space only: These are ignored. 5. COMPILER COMMANDS: Any line where # is the first non-space character is treated as a compiler command. The command is indicated by the next character (upper or lowercase) following the #. Some commands have arguments, which are assumed to begin with the next non-whitespace characters following the command. Any parameters shown here in square brackets [] are optional. The commands are: space Comment. The line will be ignored. Example: # This is a comment. D[n] xxxx Change some directive defaults (see the Directives section below), as in #DVB8C10 or #d3 hr50vmf2 or #d9JLJBC This command affects only those lines following it. Scripts may contain as many #D commands as you like. There are 10 default directives available for you to set. Specifying #D is the same as #D0 -- this sets the general overall default directive when a title line contains no directive or when just the D directive is present. The directives D1 - D9 may be set for situations when you need a shorthand way to represent a long complicated directive string in many places in your script. Directives D0 - D9 are initially all identical, according to your DIRECTIVE setting in JACOsub.cfg. Fn <fontname.font> <size> [CLEAN or QUICK&DIRTY] This command sets font <n> to <fontname.font> which is <size> pixels high. CLEAN or QUICK&DIRTY indicate the rendering mode for the font, and if omitted will default to CLEAN. This works the same as the FONT setting in JACOsub.cfg (see JACOsub.doc for a complete explanation). The n argument may range from 0 to 9 if the software has been registered, otherwise n may range from 0 to 3. Font settings affect the entire script. #F commands should be specified before any timed lines in your script. Example: #F 2 Diamond.font 20 quick&dirty I <time> <filename> Include another script file <filename> into the current script, offsetting the second script's start time by <time>. This command is useful, for example, if you are subtitling a series of TV shows having subtitles for credits and ending song lyrics. Rather than importing and/or re-timing the same sequences over and over again for each episode, you need only time the song lyrics once and the credits once, with the times starting at zero, and save these two scripts as separate files. When your "main" script includes these other scripts, they will be incorporated properly into the main script to start at the proper time (which is <time> added to the first time event in the included script), and any overlapping time ranges will be interwoven properly. <time> is specified in the form H:MM:SS.FF, where H is an hours digit, M is a minutes digit, S is a seconds digit, and F is a fractional-second digit. The units of F are determined by the #T command (below), and default to 30 units/second if the #T command was omitted (that is, the FF digits are SMPTE units ranging from 00 to 29. The included script may in turn contain its own, possibly different, #T command, and also its own #Include commands. <time> always offsets the "includee" relative to the beginning of the "includer," taking into account the "includer's" offset if the "includer" was itself included by some other script. <filename> may be any valid path + file name. <filename> can specify a complete path; if no path is specified then JACOsub will look in the default scripts directory, which you can set in JACOsub.cfg If you omit the extension in the filename, then the program will include the script with the most recent time-stamp, among the extensions .js, .tts, .pjs, or .tim (.jsc, .pan, or .sub files won't be considered). Any occurrences of #F, #P, #Q, #R, and #S in an included script will be ignored. These commands work only in the primary script, and they affect all included scripts. The effects of #D and #T commands are passed down into included scripts, but these commands inside an included script affect only that script and others IT might include; they have no effect on the higher-up "calling" scripts. Example: #I 0:21:44.16 scripts:kor/kor-credits.js Pn r g b = Palette setting. This sets the red, green, and blue intensities for color register n, to r, g, and b, respectively. This command may be specified anywhere in the file, but the setting will be used for the entire script. Use intensities of 14 or 15 with caution, as these are stronger than normal video signals, and can result in color bleeding when using in your genlocked video signal. Examples: #P1 14 14 6 #p 3 0 13 0 Qn Quantize. This command has the effect of eliminating timing gaps between subtitles of less than n/100 seconds (regardless of the units specified by the #T command). Default is #Q0. Example: With #t30 and #q4 specified, any time event less than 4/100 seconds (about one 1/30 second unit) earlier than another time event will be rounded up to the more recent event. This is of questionable usefulness. Rn Ramp time. If you play a pre-timed script, and discover a time drift, then use this command. The parameter n is the number of seconds of drift over the entire script. Script timings will be adjusted appropriately according to the value of n. A positive value will lengthen the total script running time, and a negative value will shorten the total script running time. The default value is #R0. Examples: #R-3.6 will shorten the script running time 3.60 seconds. #R .92 will lengthen the script running time 0.92 seconds. Sn Shift time. This is useful to correct for human error delays. The parameter n is the number of seconds to shift each time event in the script. A positive value will delay each time, and a negative value will advance each time. 0 to -0.2 seconds is about right for human errors in timing. The default value is #S0. Example: #S -0.2 will cause all events to occur .2 seconds sooner than usual. Tn Time units per second. The default is SMPTE units of 30 counts/second, as in #T30. If your script is in units 1/100 second units or PAL units, you must say so with the appropriate command, before the subtitle text begins. Example: #t 100 6. TIMING LINES for the script may occur in any order. They look similar to this: H:MM:SS.FF H:MM:SS.FF directive {comment} text {comment} more text... Here's what all those things are: The first field is the time when the subtitle is to appear on the screen. The normal default is SMPTE format (that is, FF can range from 00 to 29). Use the #T command (described above) to change units. IMPORTANT: The FF digits represent time units, NOT fractions of a second. There is a difference. For example, if you use #T10 to specify 1/10 second time units, then a time such as 0:00:00.60 would be illegal (and result in an error) because it specifies 60 time units! 0:00:00.6 or 0:00:00.06 or even 0:00:00.00006 would be correct for this case -- 6 UNITS are specified, not 6 tenths of a second. The second field is the time when the subtitle is to disappear. The next field is the directive. It is optional. If you leave it out, the program will default to standard subtitling form (all text centered at the bottom of the screen depending on how you have your global default directive set up), and the text MUST begin with a non-alphabet character {such as a comment}. Directives are explained fully in the Directives section below. The first non-whitespace character following the directive is assumed to be the beginning of the subtitle text. The {comment} is considered a part of the subtitle text, but it is ignored by the software. Use it for character names or keywords. A comment must be enclosed in braces. Comments may appear anywhere within the text of a subtitle. If you really want to to display a left brace, precede it with a backslash like so: \{. Right braces will be interpreted as a literal character or close of a comment, whichever seems appropriate. If a whitespace character immediately follows a comment closing brace, then that first whitespace character will be ignored. Any other kind of following character will be considered part of the subtitle text, and used. Comments in the text are especially useful when translating foreign films -- we use them to list possible translations of phrases we are not yet sure about. The "text" and "more text" fields are what gets displayed. There are several special codes that you can put inside the text (CASE IS IMPORTANT HERE ONLY): \n Newline. This is like a carriage return. A line containing this code will be split into two. Each of these new fragments will then be word-wrapped separately unless you turn wordwrapping off (see the W directive below). Useful for general formatting. Multiple \n codes may be concatenated to create blank lines. Example: Hello!\n\nHow are you?{blank line separating the two} \{ Display a left brace. Left braces are normally used to indicate the beginning of a comment. \~ Display a tilde. Tildes are normally used to create "hard" spaces (see below). \\ Display a backslash. Backslashes are normally used to denote these special codes. \N Normal. All text appearing after this code will be displayed in "normal" style. This is typically the default, unless you have the style (S) directive set to something other than normal. \I Italics. Display all text appearing after this code in italics. Example: \IHello!\N\nHow are you?{Hello is in italics} \B Boldface. This one isn't particularly useful, but go ahead if you feel like it. \U Underline. This is virtually useless for large color text. \Cn Color n. The text following this code will be displayed using face color n. n is a hexadecimal digit; it may take the values 0-9 or A-F (or a-f). Typically, when using the font supplied with this software on a 2-bitplane display, only colors 3 and 1 are useful. See the C directive below for some caveats about colors. THE LAST 5 CODES ABOVE AFFECT ONLY ONE TIMING LINE; their effects do not carry over into other lines. These codes override any directives. The \I, \B, and \U codes are mutually exclusive: You can have bold text or italic text, but you cannot create text that is BOTH bold and italic. See the demo script file (demo.js) for good examples on usage. Leading or trailing space in subtitle text will be ignored. If you want to encode a true space on the ends of some text, use a tilde (~). It will be displayed as a space in a title. To actually display a tilde, precede it with a backslash: \~. Tildes may also be used to create "hard" spaces; they will be displayed as spaces but the text will not be word-wrapped on these spaces. White space between line arguments may consist of any amount of spaces or tabs. Tabs inside the subtitle text will be converted to spaces. Directives ---------- The directive is a string that determines the subtitle's position, font, style, color, and so forth. The directive string consists of character codes, each beginning with an alphabet character followed by arguments made up of other alphabet characters and numbers. Directives may contain any of the following codes, in any order. The directives may be uppercase or lowercase. Like the text codes above, directives only affect a SINGLE timing line; their effects do not carry over into other lines. Any parameters shown here in square brackets [] are optional. Vertical positioning group: VB[n] Bottom. Position last line at the bottom (default). The offset from the bottom of screen n is optional - it says how many raster lines to offset from the physical bottom-of-viewport. VB by itself is the same as VB16 (in the original distribution of this software). The default value of n can be changed using the DIRECTIVE setting in JACOsub.cfg, or with the #D command. VM Middle. Equal blank space above and below the text. VT[n] Top. Position the title with the first line at the top. The offset n is optional - as with VB, VT by itself is the same as VT16 in the original distribution of this software. VLn line n. Position subtitle starting at text line n (the height of a line depends on the font you use). n=0 for top line. VPn Pixel n. Position subtitle so that the font baseline of the first line of text is n pixels from the top of the viewport. You need to know your font's baseline position for this directive to be of any use. VU Continue this line directly Underneath the previous one. This is useful if you have to display more text than your editor will allow on a line. You can also use it to create interesting effects when a line with the VU directive is timed so that it's not on the same display as the previous line. For example, suppose you had a single line that used the VM directive. Normally it would be perfectly centered vertically on the screen. However, if a VU line follows it, both are positioned as if they were a block of lines to be centered on the screen together; i.e. the VM line will appear slightly above center and the VU line will appear slightly below center, regardless of when they are individually displayed. Had VB been used instead of VM, the first line would have appeared 1 text line higher than bottom, just enough to make room for the second line. Horizontal positioning group: HLn Left margin. Set left margin at a position that is n% of the the screen width. Default is HL1 (1% from left edge). HRn Right margin. Set the right margin at a position that is n% of the screen width. Default is HL99 (1% from right edge). The right margin MUST be greater than the left margin. Text justification group (related to horizontal positioning): JC Center. Text is centered within H constraints (normal default). JL Left. Align left edge of text at the HLn margin position. JR Right. Align the right edge of text at the HRn margin position. Block justification group (related to horizontal positioning): JBC Justify block center. Because of word-wrapping, the width of a text block will never occupy the full width specified in your margin settings. This directive positions the imaginary rectangle occupied by the text in the center of your margin settings, regardless of the text justification directives. For example, the JL directive by itself might produce the following effect (the | character indicates margin boundaries): | The quick brown fox | | jumped over the lazy dog. | but the JL directive together with JBC will preserve the text justification but center the block of text between the margins: | The quick brown fox | | jumped over the lazy dog. | JBF Justify block full (default). Text will be positioned according to whatever text justification directives are in effect, using the full width specified by the current margin settings. JBL Justify block left. Position the text block at the left margin. JBR Justify block right. Position the text block so that the right edge is at the right margin. Word wrapping group (related to horizontal positioning): W0 Disable automatic word wrapping. This may result in your text not fitting within the position constraints defined with H & V. There is really NO reason at all why you would want to turn off word wrapping; you can wrap words manually with the \n code whether word wrapping is on or off. This directive is here just for the sake of completeness. W1 Automatic "smart" word wrapping (default). Even if a your text contains hard return codes, the separate substrings will be word- wrapped if necessary. This word wrapping mode uses a "smart" algorithm that attempts to minimize the area of the screen occupied by the title. In this mode, you will never see a line wrapped as shown (the | characters indicate margin boudaries): | The quick brown fox jumped over the lazy | | dog. | Instead, the W1 alghorithm will attempt to minimize the text area without using any extra lines, resulting in: | The quick brown fox | | jumped over the lazy dog. | This is easier for the viewer to read. Same margins, same number of lines, but the lines are more equal in length. W2 Automatic "stupid" word wrapping. If you are disconcerted by words not completely filling the horizontal margin space, and you don't mind having a single word hanging by itself on the last line (as in the first W1 example above), then use this directive. This is the standard text-editor wordwrap algorithm, which makes no attempt at aesthetics. Why anybody would want to use this is beyond me, but here it is. \n codes behave the same as with W1. Font group: Fn Use font n, where n is a number from 0 to 9 (JACOsub loads four fonts, which you can specify in the file JACOsub.Config). The usual default font is 0, which is what you should use as your "primary" font. Fonts 4-9 are unavailable if the software is unregistered. FQ Quick&Dirty text. Text color 3 is always quick. Other colors must normally be rendered one character at a time to avoid interference between the shadow and face color when the font characters overlap when rendered (like the JACOsub font). This interference happens because of a fault in the way the Amiga renders text. The FQ directive forces all text on a line to be rendered in quick mode as if it were color 3. This is useful for speeding things up if your font does not have overlapping portions (such as TurboTitle's fonts). FC Clean rendering. Only color 3 will be rendered fast, other colors will be rendered so that the face color is not disturbed. You can use this directive to negate, on a single line, a global FF directive set using the #D command, or to override a QUICK&DIRTY setting in JACOsub.cfg. The demo script demo.js tricks JACOsub into generating "slow" clean text in the foreground display so you can see how it is. If you are curious to see how the Amiga messes up color 1 text if it's displayed the quick way, run the demo after inserting the global command #DFQ at the top of the file demo.js before you play the demo. FD Default text rendering. Rendering will be "quick" or "clean" depending on how your font was set up in JACOsub.cfg. This directive is useful for overriding a #DFC or #DFF command. FOn Generate an outline around the font, n pixels wide. Color 2 (JACOsub's outline color) is used to generate the outline. This directive is useful for transforming a plain mono-color Amiga font into a nice titling font, especially when combined with the FS (font shadow) directive. Recommended value for n is 2, which produces a nice flicker-free outline. n must be less than 127. The default value is zero. WARNING: Generating outlines can slow the program down considerably! It is recommended that you use this directive only with QUICK&DIRTY font rendering, preferably with mono-color fonts. FSdn Generate a font shadow, taking into account any existing font outline, in direction d, and n pixels deep. Color 2 (JACOsub's shadow color) is used to generate the shadow. The direction d is specified as compass directions: N, S, E, W, NW, NE, SW, SE. Good values to use for the shadow depth n are 2 - 5. The warning about font outlines above applies here also. Example: FSSE3 produces a shadow similar to the JACOsub 29- pixel font, with the shadow extending down and to the right. Style group (related to font group - may also be set with text codes): SN Normal style (typical default). SI Italic. SB Bold (using the JACOsub font, this doesn't look good with colors other than color 3). SU Underline (ugly! Not recommended). Color group (related to font group - CFn may also be set with text codes): CFn Use color register n for the face color of the font. JACOsub assumes that all color fonts use bitplane 0 (i.e. color 1) for the face color, and bitplane 1 (i.e. color 2) for the shadow/ outline. THIS IS IMPORTANT! JACOsub will generate text differently depending on the color selected (see FF above). The foreground color may also be set using the \Cn code inside the text. CBn Use color register n for the background color. The display will be cleared to this color prior to building the text. If two lines share the same display, and they have different background colors specified, the screen will be cleared using the latest NON-ZERO background color that occurs for that display. In other words, non-zero colors override the default zero (transparent) background color. CSn[:s[:c]] This causes text to appear inside a shaded rectangle. The rectangle will be large enough to contain the text with a margin of n pixels on all sides. The shading is user-defined (with the SHADEPATTERN setting in JACOsub.cfg) if s=0, or solid if s=1. Color c will be used for the rectangle. The style (s) and color (c) paramters are optional; not setting them uses the defaults, normally s=0, c=2 (user-defined, black). Setting n=0 disables the shading. We suggest using n=8 or more. Only ONE shaded background rectangle will appear on the screen. JACOsub will attempt to create a SINGLE box which contains ALL text that uses the CS directive. If two shading directives for the same time range conflict, one of them will be used, but predicting WHICH one is impossible! The normal default setting is CS0:0:2, which can be changed using the #D command or the DIRECTIVE setting in JACOsub.cfg. Notes: Setting VB0 will mean that bottom-positioned text is as low as it will go, therefore no shading can appear below it. You should set the VB directive so that there is room for the shading rectangle to extend below the text. Also, VB text will be repositioned slightly higher when the running clock is displayed during play, but shade boxes will NOT be repositioned. Genlock group (for Digital Creations' SuperGen only; others later): GBn[Tm] Move the background slider control to n% saturation over a time period of m/60 seconds of time. n may range from 0 to 100. If time specifier is omitted, it defaults to 0 (i.e. instant). Example: GB63T120 slides the background fader to 63% saturation in 2 seconds (120/60 seconds). GGn[Tm] Move the graphics slider control to n% saturation over a time period of m/60 seconds of time. >> DO NOT USE THE G DIRECTIVES WITH THE GLOBAL #D COMMAND OR IN JACOsub.Config, or the genlock will be have control signals sent to it at every time event. IFF group (for loading IFF files) IL <ILBM file name> [<x offset %> <y offset %>] Load and display an IFF ILBM file for the time interval specified by the start and stop time. When this directive appears, JACOsub assumes that the remainder of the line is information about the file, NOT title text. The file name must follow the directive string. The position to display the image, specified as percent of screen width and height from the center, can be specified in the next two fields. These position coordinates default to 0 0 if they are omitted, which results in the picture being centered on the screen. The picture may be positioned to extend beyond the display edge. Any IFF ILBM picture or brush may be specified. As many as 40 images may be loaded onto a single screen. This enables you to create several small brushes and display them all at once, in different areas of the screen. CAVEATS (READ CAREFULLY!): 1. You need at least AmigaDOS 2.0 to use this directive. Under 1.3 and below, this directive is ignored. 2. You will not be informed if a file is too big to fit in memory. If this happens, the file will simply not load. 3. If the IFF file contains more bitplanes than the JACOsub video buffers, the EXTRA BITPLANES WILL BE IGNORED. You may change the number of JACOsub's bitplanes in JACOsub.cfg. If you have JACOsub set for a 4-color (2-bitplane) screen, and you try to load in a 16-color (4-bitplane) picture, you will lose 2 biplanes of information, and the picture will look strange when it appears. 4. All pictures are treated as IFF brushes. Therefore, your picture, once loaded, will use JACOsub's color palette. THE PICTURE'S OWN COLOR PALETTE WILL BE IGNORED. Create your graphics using the same palette you use with JACOsub or the picture will look strange when it appears. 5. JACOsub attempts to load the IFF files as they are needed. This can cause a video switch delay if a time event occurs while a file is loading. Keep your IFF images on a fast hard disk, or better yet, in RAM:. If you do not have sufficient memory, then do not use this directive! Default group (when you don't need a directive) Because all of the above directives are optional, there is one other set of directives that may be used when you do not wish to specify any: D or D0 Default. To be used if no other directives are used. You don't even need this directive at all, if your text begins with a non-alphabetic character (such as a {comment}, number, etc.). Specifying D (or nothing) will use the program's default settings. The default directive for JACOsub is normally HL1HR99VT16VB16JCJBFF0FDFO0FSSE0SNCF3CB0CS0:0:2W1 which you can change in the file JACOsub.Config, or with a #D command at the top of your script. Confused? Here they are spaced out: HL1 HR99 VT16 VB16 JC JBF F0 FD FO0 FSSE0 SN CF3 CB0 CS0:0:2 W1 The Genlock directives should NEVER be specified globally, nor in JACOsub.Config. Dn The directives D1 - D9 may be defined with the commands #D1 - #D9. You can use these "default" directives as shorthand for more complex directives that you may need in many places. If you put two D directives in the same directive string, the latest one will be used, and any previous directives ignored. If a directive string contains conflicting information, the information occurring last will be used. For example, VTD will cause VT to be ignored in favor of the default. In the directive CF10JLCF3, CF10 will be ignored in favor of CF3. Naturally, any directive beginning with D is unaffected by the D. In the long default directive above, you can see VT16VB16. This serves to set the top-of-screen offset to 16 for later, and then says that now the default vertical positioning will be 16 pixels from the bottom of the viewport. Sample Lines ------------ These 4 lines all have the same effect. Note that any spaces after the directive and the first space after comments are ignored. 0:00:10.11 0:00:12.00 D {fudo-ikiteru} It's alive! 0:00:10.11 0:00:12.00 D {fudo-ikiteru}It's alive! 0:00:10.11 0:00:12.00 D It's alive!{line doesn't start with a comment} 0:00:10.11 0:00:12.00 {fudo-ikiteru} It's alive!{starts with a comment} If you want leading/trailing spaces, all of these lines will do the same thing (put two spaces in front of and after the text): 0:00:10.11 0:00:12.00 D ~~{fudo-ikiteru} It's alive! ~ 0:00:10.11 0:00:12.00 D {fudo-ikiteru}~~It's alive!~~ 0:00:10.11 0:00:12.00 D {fudo-ikiteru} ~~It's alive!~~ 0:00:10.11 0:00:12.00 D ~ It's alive!~~ 0:00:10.11 0:00:12.00 ~~{fudo-ikiteru} It's alive! ~ 0:00:10.11 0:00:12.00 {fudo-ikiteru}~ It's alive!~~ 0:00:10.11 0:00:12.00 {fudo-ikiteru} ~~It's alive!~~ 0:00:10.11 0:00:12.00 {fudo-ikiteru} It's alive!~~ THE FOLLOWING LINE IS BAD. It needs either a directive after the timing numbers, or a comment to indicate that subtitle text follows the timing numbers. Any alphabet character (A-Z, a-z) following the timing numbers MUST be part of a directive. 0:00:10.11 0:00:12.00 It's alive! For the next line, use color 1 for the font face color, start the subtitle at the top of the screen and leave the other defaults alone, and cause one word to be displayed in italics: 0:02:23.23 0:02:25.01 cf1vt {thug1-nani} Whaddaya \Imean\N, ``please?'' Note: Normal quotation marks ("like this") may be used, but using a double grave and a double apostrophe, as in the line above, looks more professional on the screen. Just make sure that the grave looks like an upside-down apostrophe in your font, and that both characters occupy a narrow space. The JACOsub fonts are designed this way. Additional note (THIS IS ONE OF THE BIG FEATURES OF JACOsub): Timings may overlap! The software will handle overlapping text displays properly, but you must be sure to position your subtitles so that these separate text events do not physically overlap on the screen. You can arrange timed lines in any order you want, separate overlapped events into groups, or whatever. The program will handle it. Credits ------- The original JACOsub format was dreamed up by Alex Matulich and Daric Koslowski, before any code was ever written for JACOsub. Yes, this was the second step! (The first was to create the fonts.) Beta testers and users have been very helpful in expanding and improving the specification into what it is today. User feedback has played a large role in the development of the software and the script format.